home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / dsysvx.z / dsysvx
Encoding:
Text File  |  2002-10-03  |  10.4 KB  |  265 lines
  1.  
  2.  
  3.  
  4. DDDDSSSSYYYYSSSSVVVVXXXX((((3333SSSS))))                                                          DDDDSSSSYYYYSSSSVVVVXXXX((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      DSYSVX - use the diagonal pivoting factorization to compute the solution
  10.      to a real system of linear equations A * X = B,
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      SUBROUTINE DSYSVX( FACT, UPLO, N, NRHS, A, LDA, AF, LDAF, IPIV, B, LDB,
  14.                         X, LDX, RCOND, FERR, BERR, WORK, LWORK, IWORK, INFO )
  15.  
  16.          CHARACTER      FACT, UPLO
  17.  
  18.          INTEGER        INFO, LDA, LDAF, LDB, LDX, LWORK, N, NRHS
  19.  
  20.          DOUBLE         PRECISION RCOND
  21.  
  22.          INTEGER        IPIV( * ), IWORK( * )
  23.  
  24.          DOUBLE         PRECISION A( LDA, * ), AF( LDAF, * ), B( LDB, * ),
  25.                         BERR( * ), FERR( * ), WORK( * ), X( LDX, * )
  26.  
  27. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  28.      These routines are part of the SCSL Scientific Library and can be loaded
  29.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  30.      directs the linker to use the multi-processor version of the library.
  31.  
  32.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  33.      4 bytes (32 bits). Another version of SCSL is available in which integers
  34.      are 8 bytes (64 bits).  This version allows the user access to larger
  35.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  36.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  37.      only one of the two versions; 4-byte integer and 8-byte integer library
  38.      calls cannot be mixed.
  39.  
  40. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  41.      DSYSVX uses the diagonal pivoting factorization to compute the solution
  42.      to a real system of linear equations A * X = B, where A is an N-by-N
  43.      symmetric matrix and X and B are N-by-NRHS matrices.
  44.  
  45.      Error bounds on the solution and a condition estimate are also provided.
  46.  
  47.  
  48. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  49.      The following steps are performed:
  50.  
  51.      1. If FACT = 'N', the diagonal pivoting method is used to factor A.
  52.         The form of the factorization is
  53.            A = U * D * U**T,  if UPLO = 'U', or
  54.            A = L * D * L**T,  if UPLO = 'L',
  55.         where U (or L) is a product of permutation and unit upper (lower)
  56.         triangular matrices, and D is symmetric and block diagonal with
  57.         1-by-1 and 2-by-2 diagonal blocks.
  58.  
  59.      2. If some D(i,i)=0, so that D is exactly singular, then the routine
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. DDDDSSSSYYYYSSSSVVVVXXXX((((3333SSSS))))                                                          DDDDSSSSYYYYSSSSVVVVXXXX((((3333SSSS))))
  71.  
  72.  
  73.  
  74.         returns with INFO = i. Otherwise, the factored form of A is used
  75.         to estimate the condition number of the matrix A.  If the
  76.         reciprocal of the condition number is less than machine precision,
  77.         INFO = N+1 is returned as a warning, but the routine still goes on
  78.         to solve for X and compute error bounds as described below.
  79.  
  80.      3. The system of equations is solved for X using the factored form
  81.         of A.
  82.  
  83.      4. Iterative refinement is applied to improve the computed solution
  84.         matrix and calculate error bounds and backward error estimates
  85.         for it.
  86.  
  87.  
  88. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  89.      FACT    (input) CHARACTER*1
  90.              Specifies whether or not the factored form of A has been supplied
  91.              on entry.  = 'F':  On entry, AF and IPIV contain the factored
  92.              form of A.  AF and IPIV will not be modified.  = 'N':  The matrix
  93.              A will be copied to AF and factored.
  94.  
  95.      UPLO    (input) CHARACTER*1
  96.              = 'U':  Upper triangle of A is stored;
  97.              = 'L':  Lower triangle of A is stored.
  98.  
  99.      N       (input) INTEGER
  100.              The number of linear equations, i.e., the order of the matrix A.
  101.              N >= 0.
  102.  
  103.      NRHS    (input) INTEGER
  104.              The number of right hand sides, i.e., the number of columns of
  105.              the matrices B and X.  NRHS >= 0.
  106.  
  107.      A       (input) DOUBLE PRECISION array, dimension (LDA,N)
  108.              The symmetric matrix A.  If UPLO = 'U', the leading N-by-N upper
  109.              triangular part of A contains the upper triangular part of the
  110.              matrix A, and the strictly lower triangular part of A is not
  111.              referenced.  If UPLO = 'L', the leading N-by-N lower triangular
  112.              part of A contains the lower triangular part of the matrix A, and
  113.              the strictly upper triangular part of A is not referenced.
  114.  
  115.      LDA     (input) INTEGER
  116.              The leading dimension of the array A.  LDA >= max(1,N).
  117.  
  118.      AF      (input or output) DOUBLE PRECISION array, dimension (LDAF,N)
  119.              If FACT = 'F', then AF is an input argument and on entry contains
  120.              the block diagonal matrix D and the multipliers used to obtain
  121.              the factor U or L from the factorization A = U*D*U**T or A =
  122.              L*D*L**T as computed by DSYTRF.
  123.  
  124.              If FACT = 'N', then AF is an output argument and on exit returns
  125.              the block diagonal matrix D and the multipliers used to obtain
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. DDDDSSSSYYYYSSSSVVVVXXXX((((3333SSSS))))                                                          DDDDSSSSYYYYSSSSVVVVXXXX((((3333SSSS))))
  137.  
  138.  
  139.  
  140.              the factor U or L from the factorization A = U*D*U**T or A =
  141.              L*D*L**T.
  142.  
  143.      LDAF    (input) INTEGER
  144.              The leading dimension of the array AF.  LDAF >= max(1,N).
  145.  
  146.      IPIV    (input or output) INTEGER array, dimension (N)
  147.              If FACT = 'F', then IPIV is an input argument and on entry
  148.              contains details of the interchanges and the block structure of
  149.              D, as determined by DSYTRF.  If IPIV(k) > 0, then rows and
  150.              columns k and IPIV(k) were interchanged and D(k,k) is a 1-by-1
  151.              diagonal block.  If UPLO = 'U' and IPIV(k) = IPIV(k-1) < 0, then
  152.              rows and columns k-1 and -IPIV(k) were interchanged and D(k-
  153.              1:k,k-1:k) is a 2-by-2 diagonal block.  If UPLO = 'L' and IPIV(k)
  154.              = IPIV(k+1) < 0, then rows and columns k+1 and -IPIV(k) were
  155.              interchanged and D(k:k+1,k:k+1) is a 2-by-2 diagonal block.
  156.  
  157.              If FACT = 'N', then IPIV is an output argument and on exit
  158.              contains details of the interchanges and the block structure of
  159.              D, as determined by DSYTRF.
  160.  
  161.      B       (input) DOUBLE PRECISION array, dimension (LDB,NRHS)
  162.              The N-by-NRHS right hand side matrix B.
  163.  
  164.      LDB     (input) INTEGER
  165.              The leading dimension of the array B.  LDB >= max(1,N).
  166.  
  167.      X       (output) DOUBLE PRECISION array, dimension (LDX,NRHS)
  168.              If INFO = 0 or INFO = N+1, the N-by-NRHS solution matrix X.
  169.  
  170.      LDX     (input) INTEGER
  171.              The leading dimension of the array X.  LDX >= max(1,N).
  172.  
  173.      RCOND   (output) DOUBLE PRECISION
  174.              The estimate of the reciprocal condition number of the matrix A.
  175.              If RCOND is less than the machine precision (in particular, if
  176.              RCOND = 0), the matrix is singular to working precision.  This
  177.              condition is indicated by a return code of INFO > 0.
  178.  
  179.      FERR    (output) DOUBLE PRECISION array, dimension (NRHS)
  180.              The estimated forward error bound for each solution vector X(j)
  181.              (the j-th column of the solution matrix X).  If XTRUE is the true
  182.              solution corresponding to X(j), FERR(j) is an estimated upper
  183.              bound for the magnitude of the largest element in (X(j) - XTRUE)
  184.              divided by the magnitude of the largest element in X(j).  The
  185.              estimate is as reliable as the estimate for RCOND, and is almost
  186.              always a slight overestimate of the true error.
  187.  
  188.      BERR    (output) DOUBLE PRECISION array, dimension (NRHS)
  189.              The componentwise relative backward error of each solution vector
  190.              X(j) (i.e., the smallest relative change in any element of A or B
  191.              that makes X(j) an exact solution).
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. DDDDSSSSYYYYSSSSVVVVXXXX((((3333SSSS))))                                                          DDDDSSSSYYYYSSSSVVVVXXXX((((3333SSSS))))
  203.  
  204.  
  205.  
  206.      WORK    (workspace/output) DOUBLE PRECISION array, dimension (LWORK)
  207.              On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  208.  
  209.      LWORK   (input) INTEGER
  210.              The length of WORK.  LWORK >= 3*N, and for best performance LWORK
  211.              >= N*NB, where NB is the optimal blocksize for DSYTRF.
  212.  
  213.              If LWORK = -1, then a workspace query is assumed; the routine
  214.              only calculates the optimal size of the WORK array, returns this
  215.              value as the first entry of the WORK array, and no error message
  216.              related to LWORK is issued by XERBLA.
  217.  
  218.      IWORK   (workspace) INTEGER array, dimension (N)
  219.  
  220.      INFO    (output) INTEGER
  221.              = 0: successful exit
  222.              < 0: if INFO = -i, the i-th argument had an illegal value
  223.              > 0: if INFO = i, and i is
  224.              <= N:  D(i,i) is exactly zero.  The factorization has been
  225.              completed but the factor D is exactly singular, so the solution
  226.              and error bounds could not be computed. RCOND = 0 is returned.  =
  227.              N+1: D is nonsingular, but RCOND is less than machine precision,
  228.              meaning that the matrix is singular to working precision.
  229.              Nevertheless, the solution and error bounds are computed because
  230.              there are a number of situations where the computed solution can
  231.              be more accurate than the value of RCOND would suggest.
  232.  
  233. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  234.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  235.  
  236.      This man page is available only online.
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.